\chapter{Software}

% (10 pages) 
%
% * Explain how a member of the panel runs your game.
%
% * Discuss how it would be possible for someone to add new functionality to the
%   game.
%
% * Show how you maintained your software during its development.

\section{Compilation and Running}

\subsection{Windows Installer}

The simplest way to get the game running on a Windows PC is to use the
(\verb".msi") installer file. This can be obtained from the submission, or
downloaded from our website. When you have the file, double click it to begin
the install. The windows install shield will open and ask you where you would
like to install the file to. The default path is set to
\verb"C:\Program Files\Totoro\I Am Orb\", but you can change this as necessary.
Once the installation is complete a desktop shortcut will be created as well as
a shortcut in the start menu. To run the game double click on one of these
shortcuts or the original executable (\verb".exe") file located in the
installation directory.

\subsection{Building from Source: Microsoft Visual Studio}

Alternatively, the game can be compiled and run using the Visual Studio project
file provided with the submission. This is designed to work `out of the box',
providing that all of the library dependencies have been setup properly. For
more details on this, refer to the section \ref{visualstudio} on setting up
Visual Studio.

\subsection{Building from Source: Linux}

The game can also be built to run on a Linux platofrm. There are a number of
dependencies which must be installed and configured before this can be done
though. Included in the appendix is a detailed guide to setting all of these
up.  When all of these dependencies have been configured successfully, you
simply need to run \verb"./configure" to confirm that all the dependencies are
properly installed, then \verb"make" to compile the executable and then
\verb"./IamOrb" to run the game.

\section{External Libraries}

As our time developing the game was limited, we were encouraged to use third
party libraries to help with common utilities that our game needed. In our case
this included 3D graphics rendering, physics simulation, sound playback and GUI
programming.

\subsection{3D graphics}

For 3D graphics we chose to use the OGRE 3D engine. The main reasons we chose
this library included the following reasons:

\bit

\item Abstraction of the underlying API: we did not want to deal with Direct3D and
OpenGL directly as this would have been much more time-consuming and prone to
errors.

\item Intuitive object-oriented interface: meant that the library was easy to
get to grips with as we were all familiar with object-oriented design.

\item Ease of integration: although the core engine was strictly for 3D
rendering, the community had developed many useful plugins such as bindings to
physics engines.

\item Open source: meant that their was a large community of active developers
to help us, and suited our aim of also releasing our source code to the public.

\item Platform independence: as we were keen on cross-platform compatibility.

\eit

As OGRE is not a game engine, we needed to work out how the core architecture
of our game would operate. For this we chose to use the concept of different
game state classes that represent different parts of our game, all controlled
by a game state manager object. Code that implemented this system was already
available on OGRE's wiki
site\footnote{\url{www.ogre3d.org/wiki/index.php/Game_State_Manager}}. To save
time we used this code as a starting point, and modified it to suit our needs
as our game developed.

The other thing that we had to investigate was how we would create the levels
for our game and load them into Ogre. For this purpose, the Ogre community had
developed a \verb'.scene' file format. This XML-based file format was not part
of the Ogre engine by default but provided us with a standardised format of
describing an entire scene in terms of the positions and orientations of all
different objects. The primary reason we chose to use this rather than a making
our own format was because the OGRE wiki had source code for a
\verb"DotSceneLoader" class that would parse this file format. Once again, this
provided us with the perfect code base to build on.

\subsection{Physics Simulation}

The other key utility that our game required was realistic physics simulation.
As we had already decided to use Ogre as our 3D rendering engine, it made sense
to choose a physics engine that had associated bindings with Ogre.

As it seemed to be more actively used we first decided to use the Open Dynamics
Engine (ODE), with the OgreODE wrapper library. We successfully integrated
these libraries into our basic game code, but struggled when it came to using
the physics effectively. This was because the documentation and community
forums for the OgreODE wrapper library were very limited. In order to minimise
the time lost, we eventually decided to switch to a different library.

This library was the Newton Game Dynamics engine, with the associated OgreNewt
wrapper library. Unlike before, OgreNewt was very well documented and provided
many more features to automatically integrate physics into Ogre. 

Once we were confident that we had made the correct choice of physics engine, we
extended the \verb"DotSceneLoader" class to automatically create physics bodies for
each object in the level that we had tagged to have them.

\subsection{Audio Playback}

Audio was not a main feature of our game, but we felt that it was important
to include sound effects and background music in order to add to the immersive
experience of the pod and also when it was played on a normal workstation. The
most popular open source C++ audio library is OpenAL, so this was the obvious
choice. The structure of the OpenAL library is based on that of the OpenGL
library and although we had no prior experience of working with OpenGL, it
provided a straight forward interface. A wrapper object was developed for the
library to provide functions for the game to allow simple creation and
manipulation of audio sources in a 3D environment.

\subsection{GUI Programming}

% Toner I'm sure could say a bit more about this

A graphical user interface is vital in any game, but as our game was designed to
be an arcade game with a number of different levels to play it was even more
important. Many different GUI toolkits were available that could be integrated
with OGRE, but we chose to use CEGUI as it came with OGRE by default.

On first glance the CEGUI toolkit seemed to be a good choice as GUI layouts
could be created from XML-based layout files and loaded with a minimum amount
of code. However, as the project went on we had to overcome many problems with
this library, as it seemed to be too advanced for our needs. With hindsight we
should have looked into all the possibilities at the start of the project,
before we got locked into one layout file format.


\section{Content Creation Tools}

Part of OGRE's philosophy was not to limit its users to one specific set of
content creation tools, and the community provided a huge number of exporters to
convert to OGRE's internal format. The following section details the tools that
we decided to use.

\subsection{3D Modelling \& Level Design}

Maya was our preferred 3D modelling tool. The reasons we initially chose
Maya were that the majority of the group were already familiar in using it, it
was readily available to use in the department and the Maya-Ogre exporter
provided easy exporting of meshes and animations.

However, our main justification for using Maya was due to the availability of
the LFA Scene Manager plugin\footnote{\url{http://www.lfagames.com/help.htm}}.
This extended exporter allowed us to select which object in a scene we wanted to
export and then it would automatically create the mesh files along with the
\verb'.scene' XML file that we had already described to use. The exporter also
allowed us to give objects special ID tags, that could be parsed by our game, to
allow us to give special properties to objects.

Ultimately, this meant that all level design could be created using Maya, which
was vital for our plan to ensure that new levels are quick and easy to create
and integrate with the game.

\subsection{2D Graphics}

For production of all of the 2D graphics we predominantly used Adobe Photoshop
due to the experience some members of the group had with it. For simpler
tasks we used the GIMP.

\subsection{Particle Systems}

As our game progressed we wanted to add special effects in the form of particle
systems. OGRE provided a script format to create these systems without
having to explicitly code them. However, creating them by editing a script and
re-running our game to see the effects was an extremely laborious activity.
Thankfully, a number of particle system editors were available that provided a
user interface for editing particle systems, and showed the results (by using
OGRE itself) in real time.

We started off using the CEGUI-based Particle
Editor\footnote{\url{www.game-cat.com/ogre/pe/docs/index.htm}} tool.  We
quickly found though that this did not allow small particle systems to be
easily edited and the interface was quite hard to use. This meant that we
switched to using the Particle
Accelerator\footnote{\url{www.ogre3d.org/phpBB2/viewtopic.php?t=23740}}
tool. This was better because it used wxWidgets for its user interface, and its
better zooming support allowed us to easily edit our smaller particle systems.

\section{Source Code Control}

% - using Google code
% - SVN repository
% - Separate working copies
% - cross-platform development (utilities file for platform specific functions)
% - disk space shared with other pod group
% - decisions: repository location,(sourceforge, locally, google code, others,
%   trac), members of group had experience using google code, found it was pretty
%   good, uses SVN software (which group members were familiar with) and provides
%   front end
% - problems we had sharing user space, seperate working copy folders, used on
%   google account for SVN so added comments on each commit, informal rules about
%   commits: no submitting broken codes, using comments
% - temporary ban from Google Code
% - didnt use any strict coding standards maybe should have done,
% - linux and Windows:  Tortoise SVN on windows, standard svn on linux, Tortoise
%   provided useful tools for resolving conflicts, 

% deciding how we would manage our code
Before we could write any code we needed a way to efficiently manage all of our
work on a day to day basis. We decided that we would use a version control
system as it would enable us to work on different, or even the same parts of the
project at the same time and easily track and merge any changes made.
Versioning systems offer the ability to revert back to previous revisions of
code, so that a working version will always be salvageable. Several of us had
found already from the previous year's group project that such tools are
invaluable when working on large projects as a team. When working on the
previous project we had used CVS, with a repository setup locally on one of our
user spaces, but found it difficult to setup and at times, tempremental. Others
in the group had had experience with using SVN by hosting a project with Google
Code\footnote{\url{code.google.com}}, which they were very impressed with. The
options we had at this stage were to host out project on a website such as
Source Forge\footnote{\url{www.sourceforge.net}} or Google Code, or setup our
own CVS or SVN repository on a server or in the department. Hosting our code
with a website would give us flexibility of access, minimum effort setup,
security and reliability against mistakes being made with the repository. So
based on this and because of the prior experience we had in the group with it,
we decided to use Google Code\footnote{\url{totoromotionpod.googlecode.com}}.
Google Code uses SVN behind the scenes and also provides a powerful web
interface that provides features such as a wiki, bug reporting, downloads and an
excellent interface for browsing through the files in the repository and their
history of revisions; a feature that proved incredibly useful later on.

% Shared user account, working copies
As a group we were provided with a shared user account to logon to the computers
in the pod room. The account was allocated space on the departments Narcissus
server and was shared with the other group working on the pod. As we were all
working in the same space we setup individual working copies of the project for
each member. This meant we were easily able to share files from other group
member's working copies of the software. One drawback of this though, was that
when we tried to update or commit changes from the pod room computers, in order
for the Google Code site to store correctly who made the changes using their
username, we needed to log out the previous person who had made any changes,
obtain a generated password from the website, and log in. To reduce the amount
of wasted time when committing from the pod room, we decided to keep the same
account logged in and make it clear through our commit comments who had made the
changes. We adopted a strategy of always adding a comment which included our
name and changes whenever we committed changes to the repository. We also
adopted the rule of never committing code which did not compile and run properly
so as to always have a working version of the game, and also to prevent group
members spending time trying to fix bugs which probably had already been fixed.

% Linux development
In the department, we were developing the game on Windows using Visual Studio,
but most of us use Linux at home. In order to be able to continue development
from home, particularly during the Christmas and Easter holidays, we decided to
make our game compile and run on both platforms. As well as this, we wanted the
game to run without the pod as a regular computer game, to be controlled with
either the keyboard and mouse. In order to make our game work on Linux, we
located the areas where our code was platform specific and took action to work
around this. The most obvious way to get around this problem was to use the
compiler preprocessor to include different code depending on the platform.
We wanted to minimise the places where we needed to do so we isolated these
sections from the rest of the code. A good example of this was with the threads
used in the game.  Windows uses a library called \verb"process" and we were
using \verb"pthread" for Linux. Instead of every time we need to create a
thread, putting both versions of the call in a preprocessor \verb"#ifdef", we
wrote a wrapper class so this would only need to be written once and the
interface with the rest of the game code was the same for both platforms.

% bugs
Due to the small number of people working on the project and since we were
generally always coding in the same room, we decided not to use the facilities
that Google Code provided for tracking bugs. Instead we found it easier to
write our bugs on the pod room's whiteboard. This allowed us to quickly check
at a glance which bugs had not yet been fixed. Once a bug had been removed from
our code it was wiped off the whiteboard. We found as well that we did not
seriously start to consider bugs until nearer the end of the project, when it
was working as more of a complete system. Had the team been larger and the
group members in less frequent contact we would have considered using Google
Code's tool in order to make sure that the bugs were properly recorded and
being fixed. It is also possible to use the tool to maintain a list of tasks
which need doing, but we already had a method of maintaining our current tasks
that we were happy using.

% Website
As a means of promoting and distributing our game we decided to build a simple
website\footnote{\url{neutro.net/iamorb}}. The website presents the details of
the game and pictures and information about the project, the team and the game
itself. It also has details of how to obtain the source code, with a link to our
Google Code web page and has a link to download a windows installer file for our
game.

\section{Setting up Visual Studio}
\label{visualstudio}

The primary development platform for our game was Windows so we had to set up a
Visual Studio project in order to compile and run our game. As we were using a
number of external libraries we had to set up our project file so that it could
find the required header files (for compilation), static library files (for
linking) and \verb'.dll' files (for execution).

We wanted the Visual Studio project file to be independent of the specific
computers we were using, so we had to avoid using absolute file paths for the
location of dependencies. To get around this problem we decided to setup a
number of environment variables that specified the install directories of the
different libraries, which we could then use in our project file. This
meant that we could use the same project file at home, as long as the correct
environment variables were defined locally.

This technique also allowed us to share a single copy of the required library
files. This was important because we had limited space on the Narcissus server
which meant it was impractical for us all to store our own copies of the
libraries. This was even possible for the \verb'.dll' files as we could specify
Visual Studio to add the location of these files to the \verb'PATH' variable
when we ran our game.

\section{Object-Oriented Design}

C++ is an object-oriented language and we adopted this as a design method from
the very beginning. There are several examples in our project of this. All parts
of the game have been designed to be modular. For example, the input device
system has been designed to encapsulate each input device in an object. Figure
\ref{inputdevices} shows the structure of this interface and its implentations.

The \verb"InputDevice" interface was designed so that any possible object that can
control the orb would extend it. For example a mouse or replay controller
(Figure \ref{inputdevices}). Each player has an \verb"InputDevice" associated with it
which updates the player's orb. So far, in our game, there are four
implementations of \verb"InputDevice"; \verb"Mouse", \verb"Keyboard",
\verb"Joystick" and \verb"ReplayController".
Each of these turn their respective inputs into a force to apply to the orb to
control it.

There is an abstract \verb"PlayState" base class that handles everything common
between every type of gameplay; for example, updating the players and
the physics world. There are currently two extensions of it;
\verb"SingleUserPlayState" for controlling a single player as well as a ghost
and \verb"ReplayState" for controlling any number of players using any number
of \verb"ReplayControllers". Each has different implementations of functions to
handle the gameplay differently. For example \verb"SingleUserPlayState" stops
when the main player has finished, regardless of whether the ghost has (if there
is one) whereas \verb"ReplayState" only finishes when every single player has
finished.

Maintaining good object-oriented design has made the development process much
easier for us as a group. Apart from its benefit to us, it will also make any
further work on the game by others simpler and easier. The underlying class
structure of the game is simple and logical. The diagram in figure
\ref{gamestate} shows the structure of the game state classes, which
constitutes much of the game's functionality. With this structure it is clear
how it could be changed or augmented to in order to implement new
functionality.

\begin{figure}
\begin{center}
\includegraphics[scale=0.5]{images/inputdevice_uml.pdf}
\end{center}
\caption{The input device class structure}
\label{inputdevices}
\end{figure}

\begin{figure}
\begin{center}
\includegraphics[scale=0.5]{images/gamestate_uml.pdf}
\end{center}
\caption{The game state class structure}
\label{gamestate}
\end{figure}

\section{Extending the Game}

As the core concept of our game was quite simple, we made it a priority for the
game to be highly extensible. There are many different aspects of the
game that can be extended. Some can be altered without even recompiling the game,
while those that will require additional code are possible without having to
refactor any of the existing code.

\subsection{Creating New Levels for \textit{I am Orb}}

As we wrote the game we intended to make the process of creating levels to be
easy so that players could easily add their own. To do this a version of Maya is required
with the LFA scene manager plugin installed. Included in the appendix is a
detailed guide covering all aspects of level creation and should be studied
carefully before creating a level but the process is outlined here.

The geometry of a level can be created using standard polygon modelling
techniques before it can be exported with the LFA tool. Dynamic elements such
as moving platforms are created by assigning ID values to polygon shapes and
using locator points to specify paths and directions. When the scene and mesh
files have been successfully exported, the level can be added to the levels
configuration file (\verb"levels.ini") and then accessed from the game's level
select menus.

\subsection{Adding New Pickups}

Pickups in our game are implemented using a hierarchy of classes that derive
from the abstract \verb"Pickup" class. There are two main types of pickups:

\bit

\item Collectables: derived directly from Pickup, these pickups don't actually
affect the player but just add something to their game session. Examples
include life, time and score pickups.

\item Power-ups: derived from the \verb"Powerup" abstract class, these pickups affect
the player for a variable amount of time. Examples include size, invert pickup.

\eit

This object oriented framework (illustrated in figure \ref{pickups}) makes it
easy to integrate new pick-ups into the game. The specific steps required to add
a new pickup are as follows:

\begin{enumerate}

\item Create a class that extends \verb"Pickup" or \verb"Powerup".

\item Ensure the constructor of your class calls its parent class' constructor.
This specifies the graphical components that your pickup will use.

\item Implement the apply method; this method will be called when a player
collides with the pickup. A player object is passed into this function which
allows you to access any of the player specific classes. This means you can add
your pickups functionality to the required class, and apply it from this method.

\item Implement the undo method (power-ups only), this method will be called by
the \verb"PickupControl" class when the power ups effect has run out, so it should
undo the effects of the power up.

\item Edit the \verb"parseNode" method of the \verb"DotSceneLoader" class, this
is so that nodes with a specific ID tag will cause an instance of your pickup
to be added to the game.

\item Create a level with your pickup included. To do this using Maya create an empty locator
node in the position of your pickup and set its exportable ID to be the string
you specified in the \verb"DotSceneLoader" code.

\end{enumerate}

% add in refs to this
\begin{figure}
\begin{center}
\includegraphics[scale=0.5]{images/pickup_uml.pdf}
\end{center}
\caption{The pickup class structure}
\label{pickups}
\end{figure}

\subsection{Implementing Networked Multiplayer Gameplay}

One option that we had considered for the game was to have a networked
multiplayer option. We believe that a multiplayer element could be incorporated
into the game with relatively little effort. This is because we have already
designed this capability into the existing elements of the game, such as the
input device system. As well as this, the networking functionality for
communication with the pod server has been very successful. However, we felt
that we did not have enough time to implemented this feature properly. We spent
a lot of time considering how it would be implemented so that we could design
the game to provide a good structure to do so. The details of a possible
implementation are described below.

There are several areas that would need to be extended or created to allow an
implementation of a multiplayer, networked gameplay. Firstly, a multiple-user
\verb"PlayState" would need to be created. After this, new menus would be
needed and a new \verb"InputDevice" to allow control of a player over a
network. The new \verb"PlayState", for instance \verb"NetworkPlayState", would
have a single \verb"UserControlledInputDevice" for the local player and any
number of other players controlled by \verb"NetworkControllers". The game has
been proven to work with multiple players which can be seen when playing
against a ghost and when watching a replay of a user's game against a ghost.

New menus would be needed to allow users to create a game server and connect to
an existing server. This would be a fairly simple task and would just be a case
of creating a few new layouts and a couple of extra functions to set the correct
layout and provide background functionality for it.

The biggest issue that we could foresee would be the best way to implement the
\verb"NetworkController". The \verb"ReplayController" works by setting a force
on the orb and updating OgreNewt with exactly the same time-steps that occurred
during the initial run. To do this correctly with a \verb"NetworkController",
we would have to ensure that every single player has every other player's force
on the orb before they could update OgreNewt. This could drastically affect the
physics frame rate in the game and dropped connections could cause problems. It
is critical that a force is used for the player and in the replays so that
controlling contacts with teleports and end-zones etc. work properly. However,
for the purposes of playing over a network, it would be possible to explicitly
set the position of the orb. In some instances, for example when travelling
over a moving platform, the orb would appear to float over a gap because the
platform would not move (unless we set the position of that as well). We
believe that this would be acceptable because other information, such as when
the player has finished, could also be sent over the network. Once each player
has finished, their replay file can then be broadcast so that anyone can watch
their run properly afterwards. This would overcome problems with network
latency and dropped connections during gameplay but sacrifice the quality of
how the network players appear in the game. If their run can be viewed properly
afterwards though, we feel that this is the best overall solution.

\subsection{Adding New Input Devices}

Adding a new \verb"InputDevice" to our game, such as a Wii remote, would be a
very simple task. To use the Wii remote as an example, its input is already
handled by OIS so to add it to our game a wrapper class for the OIS class which
would extend \verb"InputDevice" is all that is needed. This would not be
difficult and has already been done for the mouse, keyboard and joystick. In
the case that OIS cannot handle such an input device, for example the
aforementioned \verb"NetworkController", then the class would have to be
implemented from scratch.  Once the new \verb"InputDevice" has been created, it
is just a case of adding code to select the new device into the relevant place
within the game. The diagram in figure \ref{inputdevices} shows the structure
of the input device system in the game.

% - PlayStates
% - InputDevices
% - Open source development
% - Mulitplayer possibilities
% - Level design

